﻿//==============================================================================
// File: IMultiMap.cs
// Created: 2010-05-10
// Author: Piotr Włodek
//==============================================================================
// This file is a part of MAMMOTH project.
// Copyright (C) 2010 AGH University of Science and Technology, Krakow.
// https://caribou.iisg.agh.edu.pl/trac/mammoth
//
// Mammoth is free software: you can redistribute it and/or modify
// it under the terms of the GNU Lesser General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
// 
// Mammoth is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
// GNU Lesser General Public License for more details.
// 
// You should have received a copy of the GNU Lesser General Public License
// along with WpfRcp. If not, see http://www.gnu.org/licenses/.
//==============================================================================

using System;
using System.Collections.Generic;

namespace WpfRcp.PropertyModel.Collections
{
    /// <summary>
    /// Base interface for a multi map.
    /// </summary>
    /// <typeparam name="TKey">Type of the key.</typeparam>
    /// <typeparam name="TValue">Type of the value.</typeparam>
    public interface IMultiMap<TKey, TValue> : IEnumerable<KeyValuePair<TKey, ICollection<TValue>>>
    {
        /// <summary>
        /// Gets the values associated with the specified key.
        /// </summary>
        /// <param name="key">The requested key.</param>
        /// <returns>A list of values associated with the key.</returns>
        ICollection<TValue> this[TKey key] { get; }

        /// <summary>
        /// Gets a collection containing the keys in the Multimap.
        /// </summary>
        ICollection<TKey> Keys { get; }

        /// <summary>
        /// Gets a collection containing the lists of values in the Multimap.
        /// </summary>
        IEnumerable<ICollection<TValue>> Values { get; }

        /// <summary>
        /// Adds an item.
        /// </summary>
        /// <param name="key">The key to store the value under.</param>
        /// <param name="value">The value to add.</param>
        void Add(TKey key, TValue value);

        /// <summary>
        /// Removes the specified item.
        /// </summary>
        /// <param name="key">The key the item is stored under.</param>
        /// <param name="value">The value to remove.</param>
        /// <returns><see langword="True"/> if the item was removed successfully, otherwise <see langword="false"/>.</returns>
        bool Remove(TKey key, TValue value);

        /// <summary>
        /// Removes all items stored under the specified key.
        /// </summary>
        /// <param name="key">The key whose items should be removed.</param>
        /// <returns><see langword="True"/> if the item was removed successfully, otherwise <see langword="false"/>.</returns>
        bool RemoveAll(TKey key);

        /// <summary>
        /// Removes all items stored in the collection.
        /// </summary>
        void Clear();

        /// <summary>
        /// Clears all underlying collections without removing them.
        /// </summary>
        void ClearValues();

        /// <summary>
        /// Determines if any items are stored under the specified key.
        /// </summary>
        /// <param name="key">The key in question.</param>
        /// <returns><see langword="True"/> if there are items stored under the specified key, otherwise <see langword="false"/>.</returns>
        bool ContainsKey(TKey key);

        /// <summary>
        /// Determines if the specified value is stored in the collection.
        /// </summary>
        /// <param name="key">The key the value should be stored under.</param>
        /// <param name="value">The value in question.</param>
        /// <returns><see langword="True"/> if the item exists in the collection, otherwise <see langword="false"/>.</returns>
        bool ContainsValue(TKey key, TValue value);

        /// <summary>
        /// Applies the specified action to each key/value pair of the multimap.
        /// </summary>
        /// <param name="action">The action to apply.</param>
        void ForEach(Action<TKey, ICollection<TValue>> action);
    }
}